Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

VDSetPlayThruDestination

You can use the VDSetPlayThruDestination function in your application to establish the destination settings for a video digitizer component.

All video digitizer components must support this function.

pascal VideoDigitizerError VDSetPlayThruDestination
                                          (VideoDigitizerComponent ci,
                                         PixMapHandle dest,
                                         RectPtr destRect,
                                         MatrixRecordPtr m, RgnHandle mask);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

dest

Contains a handle to the destination pixel map. This pixel map may be in the video frame buffer of the Macintosh computer, or it may specify an offscreen buffer.

The video digitizer component examines this pixel map to determine the display characteristics of the video destination, including the base address, row bytes, and pixel depth. If the digitizer component does not support these characteristics, it sets the return value to badDepth . If the digitizer component cannot accommodate the location of the destination pixel map, it sets the return value to noDMA .

If you are going to use multiple output buffers, be sure to include this buffer in the buffer list that you define with the VDSetupBuffers function, which is described on VDSetupBuffers . You may call the VDSetupBuffers function before calling VDSetPlayThruDestination .

destRect

Contains a pointer to a rectangle that specifies the size and location of the video destination. This rectangle must be in the coordinate system of the destination pixel map specified by the dest parameter.

This is an optional parameter. Applications may specify a transformation matrix to control the placement and scaling of the video image in the destination pixel map. In this case, the destRect parameter is set to nil and the m parameter specifies the matrix.

If the destRect parameter is nil , you can determine the destination rectangle for simple matrices by calling the TransformRect function using the current digitizer rectangle and this matrix. For more information on TransformRect , see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime .

m

Contains a pointer to a matrix structure containing the transformation matrix for the destination video image. To determine the capabilities of a video digitizer component, you can call the VDGetDigitizerInfo function, described on VDGetDigitizerInfo , in your application.

This is an optional parameter. Applications may specify a destination rectangle to control the placement and scaling of the video image in the destination pixel map. In this case, the m parameter is set to nil and the destRect parameter specifies the destination rectangle.

mask

Contains a region handle that defines a mask. Applications can use masks to control clipping of the video into the destination rectangle. This mask region is defined in the destination coordinate space.

This is an optional parameter. Applications may use alpha channels or key colors to control video blending. If there is no mask, applications should set the mask parameter to nil .

VDPreflightDestination

You can use the VDPreflightDestination function in your application to verify that a video digitizer component can support a set of destination settings intended for use with the VDSetPlayThruDestination function, which is described in the previous section.

pascal VideoDigitizerError VDPreflightDestination(
                                          VideoDigitizerComponent ci,
                                          Rect *digitizerRect,
                                          PixMap **dest,
                                          RectPtr destRect,
                                          MatrixRecordPtr m);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

digitizerRect

Contains a pointer to a rectangle that contains the size and location information for the digitizer rectangle. The coordinates of this rectangle must be relative to the maximum source rectangle. In addition, the digitizer rectangle must be within the maximum source rectangle. For a complete discussion of the relationship between these rectangles, see "About Video Digitizer Components," which begins on About Video Digitizer Components .

If the video digitizer component cannot accommodate the specified rectangle, it changes the coordinates in this structure to specify a rectangle that it can support and sets the result to qtParamErr .

dest

Contains a handle to the destination pixel map.

destRect

Contains a pointer to a rectangle that specifies the size and location of the video destination. This rectangle must be in the coordinate system of the destination pixel map specified by the dest parameter. If the video digitizer component cannot accommodate this rectangle, it changes the coordinates in the structure to specify a rectangle that it can support and sets the result to qtParamErr .

This is an optional parameter. Applications may specify a transformation matrix to control the placement and scaling of the video image in the destination pixel map. In this case, the destRect parameter is set to nil and the m parameter specifies the matrix.

m

Contains a pointer to a matrix structure containing the transformation matrix for the destination video image. If the video digitizer component cannot accommodate this matrix, it changes the values in the structure to define a matrix that it can support and sets the result to qtParamErr . Applications can determine the capabilities of a video digitizer component by calling the VDGetDigitizerInfo function, described on VDGetDigitizerInfo .

This is an optional parameter. Applications may specify a destination rectangle to control the placement and scaling of the video image in the destination pixel map. In this case, the m parameter is set to nil and the destRect parameter specifies the destination rectangle.

If the destRect parameter is nil , you can determine the destination rectangle for simple matrices by calling the TransformRect function using the current digitizer rectangle and this matrix. For more information on TransformRect , see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime .

VDGetPlayThruDestination

The VDGetPlayThruDestination function allows applications to obtain information about the current video destination.

All video digitizer components must support this function.

pascal VideoDigitizerError VDGetPlayThruDestination
                                          (VideoDigitizerComponent ci,
                                         PixMapHandle *dest, Rect *destRect,
                                         MatrixRecord *m, RgnHandle *mask);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

dest

Contains a pointer to a pixel map handle. The video digitizer component returns a handle to the destination pixel map in the field referred to by this parameter. It is the caller's responsibility to dispose of the pixel map.

destRect

Contains a pointer to a rectangle structure. The video digitizer component places the coordinates of the output rectangle into the structure referred to by this parameter. If there is no output rectangle defined, the component returns an empty rectangle.

m

Contains a pointer to a matrix structure. The video digitizer component places the transformation matrix into the structure referred to by this parameter.

mask

Contains a pointer to a region handle. The video digitizer component places a handle to the mask region into the field referred to by this parameter. Applications can use masks to control the video into the destination rectangle. For more information about masks, see "About Video Digitizer Components," which begins on About Video Digitizer Components . If there is no mask region defined, the digitizer component sets this returned handle to nil . The caller is responsible for disposing of this region.

VDSetPlayThruGlobalRect

You can use the VDSetPlayThruGlobalRect function in your application to establish the destination settings for a video digitizer component that is to digitize into a global rectangle. The application provides the desired settings as parameters to this function. Not all video digitizer components support global rectangles.

pascal VideoDigitizerError VDSetPlayThruGlobalRect
                                          (VideoDigitizerComponent ci,
                                         GrafPtr theWindow,
                                         Rect *globalRect);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

theWindow

Contains a pointer to the destination window.

globalRect

Contains a pointer to a rectangle that specifies the size and location of the video destination. This rectangle must be in the coordinate system of the destination window specified by the theWindow parameter.

VDPreflightGlobalRect

You can use the VDPreflightGlobalRect function in your application to verify that a video digitizer component can support a set of destination settings intended for use with the VDSetPlayThruGlobalRect function (described in the previous section).

pascal VideoDigitizerError VDPreflightGlobalRect
                                         (VideoDigitizerComponent ci,
                                         GrafPtr theWindow,
                                         Rect *globalRect);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

theWindow

Contains a pointer to the destination window.

globalRect

Contains a pointer to a rectangle that specifies the size and location of the video destination. This rectangle must be in the coordinate system of the destination window specified by the theWindow parameter. If the video digitizer component cannot accommodate this rectangle, it changes the coordinates in the structure to specify a rectangle that it can support and sets the result to qtParamErr .

VDGetMaxAuxBuffer

The VDGetMaxAuxBuffer function allows applications to obtain access to buffers that are located on special hardware. Digitizer components that are constrained to a single output device can provide an auxiliary buffer to support multiple buffering.

pascal VideoDigitizerError VDGetMaxAuxBuffer
                                          (VideoDigitizerComponent ci,
                                          PixMapHandle *pm, Rect *r);


ci

Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.

pm

Contains a pointer to a pixel map handle. The video digitizer component returns a handle to the destination pixel map in the field referred to by this parameter. Do not dispose of this pixel map. If the digitizer component cannot allocate a buffer, this handle is set to nil .

r

Contains a pointer to a rectangle structure. The video digitizer component places the coordinates of the largest output rectangle it can support into the structure referred to by this parameter.